//
//  DMHashABSplitter.h
//  DualMediationSDK
//
//  Created by DualMediation on 2024/01/04.
//  Copyright © 2024 DualMediation. All rights reserved.
//

#import <Foundation/Foundation.h>

NS_ASSUME_NONNULL_BEGIN

/**
 * 哈希AB分流工具类
 * 
 * 基于MD5哈希算法的AB分流工具，用于将用户按照指定比例分配到不同的实验组中。
 * 该工具类确保分流结果的稳定性和均匀性，同一用户ID在相同配置下始终分配到同一组。
 *
 * 核心特性：
 * - 基于MD5哈希算法，确保分流结果稳定可重现
 * - 支持多组分流，可配置任意数量的实验组
 * - 严格按照设定比例进行分流
 * - 输入参数验证，确保分组比例合法
 */
@interface DMHashABSplitter : NSObject

/**
 * 根据唯一标识和分组比例进行用户分流
 *
 * @param uniqueId 唯一标识符（如用户ID、设备ID等），不能为空
 * @param groupRatios 分组比例数组，例如@[@70, @30]表示70%分到组A，30%分到组B
 *                   - 数组中所有比例之和必须等于100
 *                   - 每个比例值必须大于等于0
 * @param error 错误信息，当参数不合法时会设置相应的错误
 * @return 分组结果索引（从0开始），例如0表示组A，1表示组B；失败时返回-1
 *
 * @note 使用示例：
 * ```objc
 * NSError *error = nil;
 * NSInteger groupIndex = [DMHashABSplitter splitWithUniqueId:@"user123" 
 *                                               groupRatios:@[@70, @30] 
 *                                                     error:&error];
 * if (error == nil) {
 *     if (groupIndex == 0) {
 *         // 用户分配到组A
 *     } else if (groupIndex == 1) {
 *         // 用户分配到组B
 *     }
 * }
 * ```
 */
+ (NSInteger)splitWithUniqueId:(NSString *)uniqueId 
                   groupRatios:(NSArray<NSNumber *> *)groupRatios 
                         error:(NSError **)error;

/**
 * 场景化分流便捷方法
 * 
 * 结合用户ID和场景名称进行分流，适用于不同场景下的AB测试
 *
 * @param userId 用户ID，不能为空
 * @param sceneName 场景名称，不能为空
 * @param groupRatios 分组比例数组
 * @param error 错误信息
 * @return 分组结果索引；失败时返回-1
 *
 * @note 使用示例：
 * ```objc
 * NSError *error = nil;
 * NSInteger groupIndex = [DMHashABSplitter splitWithUserId:@"user789"
 *                                               sceneName:@"homepage_experiment"
 *                                             groupRatios:@[@60, @40]
 *                                                   error:&error];
 * ```
 */
+ (NSInteger)splitWithUserId:(NSString *)userId 
                  sceneName:(NSString *)sceneName 
                groupRatios:(NSArray<NSNumber *> *)groupRatios 
                      error:(NSError **)error;

@end

NS_ASSUME_NONNULL_END